🔧 Changes

Adds a new internal/ai/skills package that implements the core logic for downloading and installing Auth0 AI skills into local AI coding agent environments.

New package: internal/ai/skills

• agent.go — defines AgentConfig with detection logic for 20+ AI coding agents (Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Codex, Roo, Goose, and more). Exposes DetectedAgents() (lazy-cached, thread-safe), FastPriorityAgents() (priority-ordered list placing popular agents first), and ResetDetectedAgentsCache().

• download.go — downloads the auth0/agent-skills plugin from GitHub into a local directory using a tiered strategy: git sparse-checkout (preferred, requires git ≥ 2.25) → tar.gz → ZIP. All work happens in a temp directory; the target is only overwritten on success. Returns the resolved commit SHA.

• symlink.go — installs a named skill from the downloaded plugin into an agent's skills directory as a symlink (default) or a recursive copy (for agents/platforms that don't follow symlinks). Idempotent.

• lock.go — reads/writes a skills-lock.json that records the installed repo, ref, commit SHA, installed-at/updated-at timestamps, skill list, target agents, and scope (global/local). Uses OS-level file locking (flock) to coordinate concurrent access (Unix and Windows implementations).

• skill_meta.go — parses YAML frontmatter from SKILL.md files in the downloaded plugin to enumerate available skills with names and descriptions.

• fs_util.go — shared filesystem helpers (mergeDir, copyFile) used as a cross-filesystem fallback when atomic rename is not possible.

• validate.go — validates skill directory structure.

Full unit-test coverage accompanies every new file.

📚 References

• Source plugin repository: auth0/agent-skills

🔬 Testing

The new package ships with comprehensive unit tests covering:

• AgentConfig.IsInstalled() — marker path, binary PATH lookup, env var markers, empty/nil cases
• AgentConfig.ResolvedGlobalSkillsDir() — env var override, fallback, error on missing config
• SupportedAgents invariants — unique IDs, required agents present, detection-free agents, per-agent config correctness (Codex CODEX_HOME, Mistral Vibe VIBE_HOME, Copilot gh binary exclusion)
• DetectedAgents() / ResetDetectedAgentsCache() — cache consistency, filesystem state changes after reset
• FastPriorityAgents() — ordering, no duplicates, universal always last
• Download strategies, symlink/copy installation, lock file read/write, skill meta parsing

Run with:

go test ./internal/ai/skills/...